Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d10 / readut.arc / RUMANUAL.TXT < prev next >

Wrap

Text File | 1990-11-23 | 33KB | 924 lines

THE OPEN POLYTECHNIC OF NEW ZEALAND He Wharekura-tini Kaihautu o Aotearoa ╔══╗ ╔═══╗ ╔════════╗ ╚╗ ║ ╔═╗ ╔═╗ ╚═╗ ║ ╚═╗ ╔══╗ ║ ║ ║ ║ ║ ╚═╝ ║ ║ ║ ║ ╚═╬═════╗ ╔═════╗ ╔════╝ ║ ╔══╗ ╔═╗ ╔╝ ╚══╗ ╔══╗ ║ ║ ║ ║ ║ ╔═╗ ║ ╚═══╗ ║ ║ ╔══╗ ║ ╚╗ ║ ║ ║ ╚╗ ╔══╝ ╚╗ ║ ║ ║ ║ ║ ║ ╠═╩═╝ ╔═══╝ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╔═╗ ║ ╔═╗ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╔═╝ ╚═╗ ║ ╚═╝ ║ ║ ╚═╝ ╚╗ ║ ╚══╝ ╚╗ ║ ╚═╝ ╚╗ ║ ╚══╗ ║ ╚══╗ ║ ╚══╗ ╚═════╝ ╚═════╝ ╚══════╝ ╚═══════╝ ╚══════╝ ╚════╝ ╚════╝ ╚════╝ version 1.1 Copyright TOPNZ 1990 ___________(PgDn for MORE!)_________ Welcome to the READUTIL MANUAL! _______________________________ You can browse through this file using: PgDn, PgUp, End, Home and arrow keys, then Esc to quit to DOS prompt. Use "Shift + Print Screen" to print screen pages. __________________________________________ 1 THE OPEN POLYTECHNIC OF NEW ZEALAND He Wharekura-tini Kaihautu o Aotearoa READUTIL Version 1.1 A utility program to enhance your writing skills CONTENTS Purpose...................................... 1 Uses......................................... 2 What READUTIL tests.......................... 3 What do I need to get started?............... 3 Setting up your text......................... 3 Installing READUTIL.......................... 4 Telling READUTIL what you want it to do...... 5 Moving to your next test passage............. 7 Returning to your wordprocessing program..... 7 File types................................... 7 Working with other wordprocessing programs... 8 What is a "text file"?....................... 8 How to interpret READUTIL's results.......... 8 What can I do about it?...................... 9 What passives are............................ 9 How does READUTIL work?......................11 Command line and batch modes.................11 Integrating READUTIL with Microsoft WORD.....13 Summary......................................15 Suggestions..................................15 Copyright....................................15 References...................................15 Contact address..............................16 Registration form............................16 PURPOSE READUTIL is a program to give writers a measure of how easy their writing is to read and understand. It's a simple early warning system. It works with files which contain the piece of text you are writing, in either ASCII text file or in Microsoft WORD formats. You can find the readability of a complete piece of writing, or you can just choose parts of it and get results for each section. By measuring hard word content and sentence length, and identifying passive constructions, READUTIL shows you what parts of the text may need rewriting. 2 You can use READUTIL for reports, technical writing, essays, books, and speeches. It is not suitable for poetry or other similar writing. It will not produce useful results with headings or tables, but you can direct the program to leave these out and sample the text around them. Three things help to make writing easier to read: Fewer hard words; Shorter sentences; and, Fewer passive expressions. READUTIL helps you to write by Measuring the reading-level and the hard-word content, Marking the longest sentence, and Identifying passive expressions. USES You can use READUTIL 1. To repeatedly test your own writing. You can then use your wordprocessing program to reword your text. Shortening some of the long sentences, simplifying hard words, and replacing some passive expressions with active ones, can make your text more "readable". 2. To train authors to adopt clear writing techniques especially when writing instructional text. READUTIL reminds authors to write simply while composing the text, and not write difficult text which may later cost other people their time and effort to simplify. 3. To test people who wish to be writers of instructional text by analysing sample pieces of their writing. Some people write in a simple and straightforward style. Others put words together in ways that are more difficult to understand. People engaged to write instructional text should have the skills to write text for immediate use. Their natural wording style should not need much rewriting by others to make it clear to the target audience. You can use READUTIL to sort out the naturally good writers. 4. As an impartial aid to editing other people's work. The computer is an impartial judge of text. The reading index or level replaces opinion with measurement. 3 WHAT READUTIL TESTS If your document consists of plain straightforward text without any headings or tables, you can use READUTIL to give an assessment for the whole file. If your file includes headings or tables, or if you want to sample only part of it, you can test chunks of the text. READUTIL accepts text in paragraph-sized chunks. You can test as many chunks of the text as you like, and each chunk can consist of as many paragraphs as you like. Before you install and run READUTIL, you may want to read more about how to make use of this program. If so, go to the section on page 8, "How to interpret READUTIL's results". WHAT DO I NEED TO GET STARTED? To run READUTIL, you need (a) DOS 2.10 or later. Make sure your computer's clock is correctly set. READUTIL date and time-stamps its printouts. (b). A wordprocessor program. Microsoft WORD 3, 4, or 5 is suitable. So too is any wordprocessing program that produces a "text" or ASCII file (the sort of file used for telecommunicating between computers). (c) RU.EXE (READUTIL's program file). (d) The text you want to test, in a file on disk. READUTIL will run on any disk or drive on any IBM PC or compatible machine. READUTIL will run with any monitor. A co-processor will markedly increase its processing speed. SETTING UP YOUR TEXT 1. Get the computer up and running with your text loaded in your wordprocessing program ready for testing. 2. Decide which parts of your document you want to test. If your document is a letter or a short report, you will probably test it all. It is best to first read a long document and select the chunks you wish to test. Select one, two or three paragraphs which you think may 4 be the more difficult to read. Testing a long document as one chunk can give the impression that the overall readability is good. But it may conceal one or two paragraphs that are unsatisfactory. If your document is long, you will get results faster if you just test parts of it. Also, you can avoid headings or tables in your text by testing only the passages you select. For example, you may wish to test four sections that you consider to be hard reading. Mark these sections in the following way: (a) Insert three asterisks (the marker) in front of the first passage you want to test. For example ***In those early years, computers... Then note down on paper how many paragraphs you want that test section to contain. (Don't mark the end of the section - you'll tell the program later where to stop.) (b) Then move the cursor to the beginning of the second passage you wish to test, and insert three asterisks in front of that. Again, keep a note of how many paragraphs are in the second passage you intend to test. Your list will look something like this: Marker 1 4 paragraphs Marker 2 3 paragraphs Marker 3 5 paragraphs and so on. (c) Mark the beginnings of all the passages of text you want to test in this way. If you want the program to just test everything from a marker to the end of the document, you don't need to remember the number of paragraphs. The program will automatically run on through the rest of the document. (d) Later, you can use your wordprocessor's Search and Replace facility to delete all the *** markers. 3. Now quit from your wordprocessing program but remember to SAVE YOUR FILE. INSTALLING READUTIL Copy the READUTIL program file RU.EXE to the same disk and directory as your text. This is so you will not have to enter the full path details to run READUTIL. 5 For example, on a twin-floppy disk machine, you will probably have your wordprocessor program on a disk in the A drive and your text file on a disk in the B drive. In this case, put your READUTIL disk in the A drive and copy RU.EXE on to the disk in the B drive. To do this at the A> prompt, type copy <spacebar> RU.EXE <spacebar> B: <Return> Then return your wordprocessor disk to the A drive. To access READUTIL which is now on disk in the B drive, first get to the B> prompt by typing at the A prompt B: <Return> TELLING READUTIL WHAT YOU WANT IT TO DO At the prompt for the drive where you have installed READUTIL, type RU <Return> You will then be in READUTIL. The entry panel will appear, showing a set of prompts. This is how to use it: Path and filename <F1> Press <F1> and then type in the filename of the document you want to test. Then press <Return>. If you haven't copied RU.EXE to the same disk or directory as the test file, you will need to type in the file path as well. If you don't put a full stop or an extension after the filename, the program will add a .DOC extension when you press <Return>. Paragraph terminator <F2> READUTIL can recognise the end of a paragraph by either a double or a single carriage return. This is important because the program must be able to recognise and count paragraphs correctly. Pressing <F2> toggles from double to single carriage return. It is usual to leave it at double. Your choice depends on the wordprocessing program you are using and whether a style sheet is in use. Use the single option if you are using Microsoft WORD with a style sheet. Use the single option too if you get the WORD error message "Style sheet not available" when you load your text into WORD. 6 If your test shows that the sentence or word count is widely different from what you expected, re-run the test using the other paragraph terminator. There must be text between carriage returns for it to count as a paragraph. For this reason, both the single and double options may give the same results in some cases. Marker search <F3> Use this to tell READUTIL to test the complete file, or to test from the inserted markers (***). Press <F3>. First enter the marker's number, press <Return>, and then the number of paragraphs you want to test in that section. If you want READUTIL to test from a marker to the end of the document, don't type in a number for paragraphs. Begin processing <F10> Press this to start the program processing after you've set the above parameters. The program will now test your text, or the part of it that you have marked, for hard word content, sentence length and passive constructions. As it does so, it gives a word count and displays each passive that it finds. After the test run, the results panel will appear on the screen. AT THE RESULTS PANEL The results panel gives you information about your test. The most important part is the reading level, based on the text's hard-word content and average sentence length. You should be aiming at a reading level of no more than 12. The panel also gives the number of passive extracts that it has identified. As explained later, you'll need to check them in their context. The panel also includes a set of prompts. Mark longest sentence <F5> Press <F5> to mark the end of the longest sentence with a #. If you want to remove that mark before leaving the results panel, press <F5> again. After leaving the results panel, you will need to use your wordprocessor to remove the added mark. You can later use the "Search" or "Find" facility in your wordprocessor to locate this # in your text. Hence you can quickly find the longest sentence and make it shorter if necessary. 7 The # mark replaces the last letter in the longest sentence. The character replaced is noted on the results print-out so you can find it and put it back later using your wordprocessing program. Print-out results <F6> Press this to get a printout of the results panel and a list of passive expressions. You can find the passive expressions in the text from each expression's paragraph number and sentence number. You can also find them using the "Search" facility in your wordprocessing program. The printout also shows the number of passive expressions the program identified in the text. Changing the text to active voice will lower the number. (If you want to find out more about passive constructions, read "What passives are" on page 9.) Quit READUTIL <Esc> To get out of READUTIL, press <Esc>, read the text panel which appears, then <Y> to exit. During processing you can press <Esc> to terminate the run. READUTIL will complete the run to the end of that sentence and display the results to that point. MOVING TO YOUR NEXT TEST PASSAGE After you've printed out the results and the list of passives, you can start testing the next test passage. Do this by pressing <F10> to return to the entry panel. Here you can set up for another marker or for a new file. RETURNING TO YOUR WORDPROCESSING PROGRAM You can exit from READUTIL at any point and return to your wordprocessing program to view or to edit your text. Press <Esc> then <Y> to return to the DOS prompt. Get back to the A prompt by typing A: <Return>, then load your wordprocessing program. If you want to read more about using READUTIL with WORD, see "Integrating READUTIL with Microsoft WORD" on page 13. FILE TYPES READUTIL works directly with files written using Microsoft WORD versions 3, 4 or 5. It works just as well with ASCII "text files" with or without line breaks, written with any wordprocessing program. 8 READUTIL samples the file itself and auto-selects the correct conditions for testing WORD or plain "text" formats. WORKING WITH OTHER WORDPROCESSING PROGRAMS READUTIL will work with other text formats too, but there is no special provision for these in this current release. If you wish to test files written with some other wordprocessing program, save your file as a "text file" or plain ASCII file. Then use READUTIL. WHAT IS A "TEXT FILE"? This is a file in a form for interchanging between computers. It comprises upper and lower-case text, numerals, and the usual keyboard punctuation characters. The file may be text-only or text-only-with- line-breaks. There may or may not be a line feed and carriage-return at the end of each line. Wordprocessing programs provide a facility for generating these files for sending via a modem down a telephone line. HOW TO INTERPRET READUTIL'S RESULTS The aim of this program is to provide impartial warnings to writers about the complexity of their writing and give guidance on how to improve it. The reading level given in the results panel derives from the text's sentence length and hard-word content. The reading level is the deciding part of the results panel. If the reading level is above 12, you should edit the text. If it is below 12, you can probably leave it alone. This border at 12 is a guide and not a fixed boundary. Remember it's a tool, not a rule. Remember also that a text may have a low reading level but still not make sense - so it may still need editing. You should edit text with very high reading levels. You can best judge which texts to edit after testing several typical passages of good and poor text. Some sample texts, with manually-determined results, are included for comparison in separate files supplied with READUTIL. The files are RUWORD.DOC (in Microsoft WORD format) and the same text in RUASC.TXT (a plain ASCII text file). Load the appropriate file into your wordprocessor as you would any ordinary document or text file. 9 The batch file READ.BAT will test RUWORD.DOC and display the results. This is explained in the section "Batch operation" on page 13. The reading index or level that is finally acceptable is a matter for careful judgement. If you often use big words like "the International Telecommunication Union" (which are unchangeable except to the abbreviation ITU), the acceptable reading index must be higher. The index is a measure to see whether your writing is in step with other writing that has proved to be easy to read and understand. WHAT CAN I DO ABOUT IT? READUTIL finds the longest sentence in a tested passage and displays that sentence's word count. The # marking feature leads you to it. You can Reword the longest sentence into two shorter sentences to help to lower the reading level. Rerun the program to identify the new "longest sentence" after adjusting the first. Two or three reruns with simple editing can simplify text. The hard-word content appears as a percentage. This shows the proportion of words with three or more syllables in the text. You can Replace long words with shorter and simpler words to lower the reading-level. Use the synonym dictionary (thesaurus) in your wordprocessor for this task. With the passive text extracts printout you can Use your wordprocessor's "Search" facility to find each extract in turn. Consider each passive extract to see whether you can reword some of them and so reduce their number. Rerun the test to gauge the improvement. WHAT PASSIVES ARE Passive voice is an indirect kind of sentence construction which looks like this: B is done by A. 10 For example: The glass was broken by a boy. The boat is propelled by an outboard motor. It can also look like this: B is done. For example: The glass was broken. The computer should be switched on. Passive voice gives the impression that something just sits there while something happens to it. It tends to be wordy and longwinded. Also, the kind of sentence "B is done" doesn't show who or what does the action. The reader has to work it out. Some passive extracts are acceptable in a text, but too many make it boring to read and difficult to follow. Try to avoid using them. The active voice is a direct sentence construction which looks like this: A does B. For example: A boy broke the glass. An outboard motor propells the boat. Switch the computer on. Active voice names who or what is doing the action. It is a more straightforward way of writing. It names the subjects and their actions and makes your writing more interesting as well as easier to understand. You should encourage its use. Try to get into the habit of writing with active wording. READUTIL gives you the number of passive extracts that it has identified, and the total number of sentences it has tested. It then divides one figure by the other to form an indicator. Reduce the passives and you lower this indicator. You can process a complete file, headings and all, to get the passives identified. Remember though, that if the tested text includes tables and headings, the reading level displayed is inaccurate. You must use markers in this case, as explained earlier. The printout displays the warning << Complete File >> as a reminder. The algorithm used in READUTIL to identify the passive text extracts is simple. It will not trap all examples of passive text. But it should catch enough to show you whether your text needs attention. Also, the program may pick up a few extracts that aren't passives. Check each extract in the sentence it comes from. 11 For example, consider these two sentences: The quality of water being experienced at the moment is poor. Being experienced in this matter, I can assure you that ... The first example conforms to the formula B is done. In the second example, the past participle (experienced) is used as an adjective. In many cases you can tell the difference by putting "very" in front of the past participle. If it makes sense, then it's probably not passive (Being very experienced in this matter...). If the very doesn't make sense, the sentence is probably passive (The quality of water being very experienced...). READUTIL may also trap other extracts that are not passives. These will be obvious to you, but not to the algorithm. Two examples are "is between" and "are when". HOW DOES READUTIL WORK? READUTIL uses a reading-level algorithm based on the "Fog Index" principle given in Gunning's book (see Reference 1 below). The computer takes the average sentence length, together with the hardword content of the total passage tested, and gives a reading index. READUTIL finds sentences from the number of periods (.) in the passage. It also recognises the colon, semi-colon, exclamation and question marks (: ; ! ?) as periods (ends of sentences). READUTIL skips periods appearing as decimal points (such as 0.4) and periods following one single character (such as: A. B. Smith). It also jumps non-alphabet characters (including numerals, asterisks, hyphens, apostrophes and brackets). READUTIL finds passive text expressions by searching for forms of verbs "to be" (such as: "be", "is", "was") in combination with past participles such as found, made, learnt, given. It is a simple algorithm and will not trap all passive expressions. It should draw your attention to the importance of this aspect of writing. 12 COMMAND-LINE AND BATCH MODES The above explanation is for giving READUTIL your instructions in MENU mode. There is a faster way to tell READUTIL what you want it to do. The Command-line mode: You can enter the filename of your test file, and the marker information, all together at the DOS prompt. For example, all the information entered could look like this: RU STORY.DOC 2 4 S L P <Return> RU will run READUTIL. STORY.DOC is your file for testing. (Remember to enter the extension (.DOC) after your filename - if this applies.) 2 = Will begin the test from marker 2. 4 = It will test the 4 paragraphs following marker 2. S = The paragraph count will be by Single carriage-returns. L = It will mark the Longest sentence. P = It will Print the results and exit to DOS. These command-line parameters are an alternative method for entering instructions into READUTIL. You must separate the parameters with ONE space. The entries may be in any order and in upper or lower case. The program will read the first numeral as the marker number, and the second as the number of paragraphs. You can leave parameters out: If you omit both the marker and the paragraph numbers, the test will be for the whole file. If you omit the figure for the number of paragraphs, the test will be from the marker to the end of the file. If you omit the S, the paragraph count will be by double carriage-returns. If you omit the L, the longest sentence will go unmarked. If you omit the P, READUTIL will stop at the results panel. If you do not enter the command-line detail correctly, a "help panel" will display and give details of the correct syntax. 13 If READUTIL and your text file are in different directories or on different disks, you may need to enter the full DOS path detail for both files. For example: C:\WORK\RU B:\STORY.DOC if RU.EXE is in the WORK directory on C drive, and your file STORY.DOC is on a disk in B drive. Batch operation: You can use a DOS batch file to test sequences of texts following numbered markers. It can print out the results as it goes. Unattended operation is possible. The companion file READ.BAT is an example. Just put the READUTIL disk in your A drive, type READ at the DOS prompt, then press <Return>. Some selections in READ.BAT have L included to mark the longest sentence. The file is: ECHO OFF CLS ECHO CHECK THAT PRINTER IS ON-LINE . . . PAUSE RU RUWORD.DOC 1 1 P RU RUWORD.DOC 2 4 P L RU RUWORD.DOC 3 4 L P RU RUWORD.DOC 4 1 L P RU RUWORD.DOC 5 2 P RU RUWORD.DOC P CLS This separately tests all 5 test passages in the file RUWORD.DOC and then tests the whole file - automatically. Try it! You can write your own similar batch files to test multiple passages on any of your own documents. Load the file RUWORD.DOC (or RUASC.TXT) into your wordprocessing program and print it out or read the test passages on the screen. INTEGRATING READUTIL WITH MICROSOFT WORD The command-line entry mode can make READUTIL easy to use with Microsoft WORD. When in WORD, save your file, then use <Esc> <Library> <Run>, and enter the READUTIL command-line entry you require. Press <Return>. Remember to enter the full path details for both RU.EXE and for your file. For example, if your active drive is the C drive with your text 14 in a file STORY.DOC in a directory called WRITE in that drive, with RU.EXE on a disk in the A drive, the full path for the two files would be A:\RU C:\WRITE\STORY.DOC Remember to enter RU, not RU.EXE, to run the program READUTIL. The file STORY.DOC must have the .DOC extension included. With WORD 5, this method saves you having to re-enter the file details each time you test your work. You can jump between WORD and READUTIL with ease. On a dual floppy-drive machine (with no hard disk), you may have to replace your WORD disk with your DOS disk and vice versa during this procedure. This depends on where the WORD and DOS files are on the disks in the A and B drives. This method may not work if you have a lot of memory-resident programs. You may get strange error messages. In this case, remove some of these programs to gain extra memory or use the second choice method given below. If you use the "mark longest sentence" facility: If you use <Esc> <Library> <Run> and use READUTIL to mark the longest sentence in your file, then return to WORD and reload your file, you may find the marker is not shown on the screen. WORD does not know that READUTIL has amended your document file on the disk, so WORD has not reloaded your amended file from the disk. There are two ways to overcome this: First method: Load any other file (your backup .BAK file is suitable). Don't do anything to this, but then load your .DOC file again. Then search for the symbol # in your re-loaded original (changed) file. Second method: Don't use the the <Esc> <Library> <Run> procedure. Instead, quit from WORD and use the companion batch file (R.BAT) at the DOS command-line. Follow this method: First copy the files RU.EXE and R.BAT into the same directory as your WORD document files. (See page 5 of this Manual if you're not sure how to do this). After writing your text in WORD, save it to disk, then exit to DOS by <Esc> <Q>. Change to your WORD document file drive or directory. 15 Enter command-line details for READUTIL, BUT use R instead of RU (to use R.BAT). For example (using the example above again): R STORY.DOC 2 4 S L P <Return> This will load READUTIL, process your file, and return you to WORD again with your (changed) file loaded. SUMMARY A little care and attention can bring about great improvements to your writing. Make it easier for others to read it - so they can appreciate your work. SUGGESTIONS This software and its documentation is under constant development. Ideas for improvements are welcome. COPYRIGHT READUTIL, the file RU.EXE and supporting documents are Copyright (c) 1990, THE OPEN POLYTECHNIC OF NEW ZEALAND, all rights reserved. The software and accompanying documentation are without warranty of any kind. In the interests of improving written text, you have a limited approval. You may copy and distribute READUTIL provided you distribute it complete with all the files: RU.EXE, README, README.COM, RUMANUAL.TXT, RUMANUAL.DOC, RUMANUAL.COM, READ.BAT, R.BAT, RUWORD.DOC and RUASC.TXT. All these files must be unchanged and distributed as originally received. If after inspection you wish to use READUTIL regularly as a single user, please send your name and address with $20 to: The Manager, Information Systems, The Open Polytechnic of New Zealand, Private Bag, Lower Hutt, New Zealand. You will receive an acknowledgement which will make you a registered user. A form for this purpose is below. You may seek registration for more than a single user, or for an organisation. If so, please send details of the nature and size of the enterprise and the number of users. You will receive further information. 16 REFERENCES 1. Robert Gunning, "The Technique of Clear Writing", published by McGraw-Hill. (This is a classic reference in this field and thoroughly recommended.) 2. Fred Johnson, "Four Papers on "Readability", NZTCI, 1986", New Zealand Technical Correspondence Institute - available from the National Library of New Zealand. (NZTCI is the former name of THE OPEN POLYTECHNIC OF NEW ZEALAND.) CONTACT ADDRESS The Open Polytechnic of New Zealand, Private Bag, Lower Hutt, NEW ZEALAND Phone: +64 4 666 189, Fax: +64 4 665 633. Please tear off at this line and send to the address below: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - To: The Manager, Information Systems, The Open Polytechnic of New Zealand, Private Bag, Lower Hutt, NEW ZEALAND Date:____________ From: (your name)_____________________________________________ Address:______________________________________________________ ______________________________________________________ ______________________________________________________ Please register me as a single-user of the reading utility program READUTIL. I enclose the sum of $20. Signature: ________________________